/**
 * 用户管理API路由文件
 * 
 * 这个文件定义了所有用户相关的API接口：
 * 1. GET /api/users - 获取用户列表（支持分页、搜索）
 * 2. GET /api/users/:id - 获取单个用户详情
 * 3. POST /api/users - 创建新用户
 * 4. PUT /api/users/:id - 更新用户信息
 * 5. DELETE /api/users/:id - 删除用户
 * 
 * RESTful API设计原则：
 * - 使用HTTP动词表示操作类型（GET查询、POST创建、PUT更新、DELETE删除）
 * - 使用URL路径表示资源（/users表示用户资源）
 * - 使用HTTP状态码表示结果（200成功、201创建成功、404未找到、500服务器错误）
 */

import express from 'express'
import { User } from '../config/database.js'
// 为了兼容不同 Sequelize 版本，这里用默认导出拿到包对象，再解构出 Op。
// 小白解释：Op 是 Sequelize 的“查询操作符合集”，比如 or、like 等，
// 我们用它来写“模糊搜索”和“多个条件或匹配”。有的版本不支持直接 import { Op }，
// 所以改成从默认导出里解构，避免出现 Op 未定义的报错。
import sequelizePackage from 'sequelize'
const { Op } = sequelizePackage

// 创建路由实例
const router = express.Router()

/**
 * 获取用户列表
 * GET /api/users
 * 
 * 查询参数：
 * - page: 页码（默认1）
 * - limit: 每页条数（默认10）
 * - search: 搜索关键词（匹配姓名和邮箱）
 * - status: 用户状态筛选
 */
router.get('/', async (req, res) => {
  try {
    // 获取查询参数
    const page = parseInt(req.query.page) || 1      // 当前页码
    const limit = parseInt(req.query.limit) || 10  // 每页条数
    const search = req.query.search || ''            // 搜索关键词
    const status = req.query.status || ''            // 状态筛选
    const sortField = req.query.sortField || 'id'    // 排序字段
    const sortOrderParam = (req.query.sortOrder || 'descend').toLowerCase() // 排序方向：ascend/descend
    const sortOrder = sortOrderParam === 'ascend' ? 'ASC' : 'DESC'
    
    // 计算偏移量（用于分页）
    // 为什么要计算偏移量？SQL查询需要知道从第几条开始取数据
    const offset = (page - 1) * limit
    
    // 构建查询条件
    // where条件是什么？SQL中的WHERE子句，用于筛选数据
    const where = {}
    
    // 如果提供了搜索关键词，添加搜索条件
    if (search) {
      // 小白解释：在名字和邮箱里模糊搜索，只要包含关键词就会被匹配到
      where[Op.or] = [
        { name: { [Op.like]: `%${search}%` } },
        { email: { [Op.like]: `%${search}%` } }
      ]
    }
    
    // 如果提供了状态筛选，添加状态条件
    if (status) {
      where.status = status
    }
    
    // 执行查询
    console.log(`📋 查询用户列表 - 页码：${page}，每页：${limit}，搜索：${search}，状态：${status}，排序：${sortField} ${sortOrder}`)

    // 允许排序的字段白名单（避免传入非法字段导致报错或 SQL 注入风险）
    const allowedSortFields = new Set(['id', 'name', 'email', 'age', 'created_at'])
    const orderField = allowedSortFields.has(sortField) ? sortField : 'id'
    
    const { count, rows: users } = await User.findAndCountAll({
      where,                    // 查询条件
      limit,                    // 限制返回条数
      offset,                   // 偏移量（分页）
      order: [[orderField, sortOrder]]   // 排序规则（按指定字段与方向）
    })
    
    // 计算总页数
    const totalPages = Math.ceil(count / limit)
    
    // 返回成功响应
    res.json({
      success: true,
      data: {
        users,          // 用户列表数据
        pagination: {   // 分页信息
          current: page,
          pageSize: limit,
          total: count,
          totalPages,
          sortField: orderField,
          sortOrder
        }
      },
      message: '获取用户列表成功'
    })
    
  } catch (error) {
    console.error('❌ 获取用户列表失败：', error)
    res.status(500).json({
      success: false,
      message: '获取用户列表失败',
      error: error.message
    })
  }
})

/**
 * 获取单个用户详情
 * GET /api/users/:id
 */
router.get('/:id', async (req, res) => {
  try {
    const userId = parseInt(req.params.id)  // 从URL参数获取用户ID
    
    console.log(`🔍 查询用户详情 - ID：${userId}`)
    
    // 查找用户
    const user = await User.findByPk(userId)  // findByPk：根据主键查找
    
    // 如果用户不存在
    if (!user) {
      return res.status(404).json({
        success: false,
        message: '用户不存在'
      })
    }
    
    // 返回用户详情
    res.json({
      success: true,
      data: user,
      message: '获取用户详情成功'
    })
    
  } catch (error) {
    console.error('❌ 获取用户详情失败：', error)
    res.status(500).json({
      success: false,
      message: '获取用户详情失败',
      error: error.message
    })
  }
})

/**
 * 创建新用户
 * POST /api/users
 * 
 * 请求体：
 * {
 *   "name": "张三",
 *   "email": "zhangsan@example.com",
 *   "age": 25,
 *   "phone": "13800138000",
 *   "address": "北京市朝阳区"
 * }
 */
router.post('/', async (req, res) => {
  try {
    const userData = req.body  // 从请求体获取用户数据
    
    console.log('➕ 创建新用户：', userData)
    
    // 数据验证
    if (!userData.name || !userData.email) {
      return res.status(400).json({
        success: false,
        message: '姓名和邮箱不能为空'
      })
    }
    
    // 检查邮箱是否已存在
    const existingUser = await User.findOne({ where: { email: userData.email } })
    if (existingUser) {
      return res.status(409).json({  // 409：冲突
        success: false,
        message: '邮箱已存在'
      })
    }
    
    // 创建用户
    const newUser = await User.create(userData)
    
    console.log('✅ 用户创建成功：', newUser.id)
    
    // 返回创建成功的响应（201：创建成功）
    res.status(201).json({
      success: true,
      data: newUser,
      message: '用户创建成功'
    })
    
  } catch (error) {
    console.error('❌ 创建用户失败：', error)
    res.status(500).json({
      success: false,
      message: '创建用户失败',
      error: error.message
    })
  }
})

/**
 * 更新用户信息
 * PUT /api/users/:id
 * 
 * 请求体：要更新的字段
 * {
 *   "name": "李四",
 *   "age": 30
 * }
 */
router.put('/:id', async (req, res) => {
  try {
    const userId = parseInt(req.params.id)
    const updateData = req.body
    
    console.log(`✏️ 更新用户信息 - ID：${userId}，数据：`, updateData)
    
    // 查找用户
    const user = await User.findByPk(userId)
    if (!user) {
      return res.status(404).json({
        success: false,
        message: '用户不存在'
      })
    }
    
    // 如果要更新邮箱，检查新邮箱是否已存在
    if (updateData.email && updateData.email !== user.email) {
      const existingUser = await User.findOne({ where: { email: updateData.email } })
      if (existingUser) {
        return res.status(409).json({
          success: false,
          message: '新邮箱已存在'
        })
      }
    }
    
    // 更新用户数据
    await user.update(updateData)
    
    console.log('✅ 用户更新成功：', userId)
    
    res.json({
      success: true,
      data: user,
      message: '用户更新成功'
    })
    
  } catch (error) {
    console.error('❌ 更新用户失败：', error)
    res.status(500).json({
      success: false,
      message: '更新用户失败',
      error: error.message
    })
  }
})

/**
 * 删除用户
 * DELETE /api/users/:id
 */
router.delete('/:id', async (req, res) => {
  try {
    const userId = parseInt(req.params.id)
    
    console.log(`🗑️ 删除用户 - ID：${userId}`)
    
    // 查找用户
    const user = await User.findByPk(userId)
    if (!user) {
      return res.status(404).json({
        success: false,
        message: '用户不存在'
      })
    }
    
    // 删除用户
    await user.destroy()
    
    console.log('✅ 用户删除成功：', userId)
    
    res.json({
      success: true,
      message: '用户删除成功'
    })
    
  } catch (error) {
    console.error('❌ 删除用户失败：', error)
    res.status(500).json({
      success: false,
      message: '删除用户失败',
      error: error.message
    })
  }
})

// 导出路由实例
export default router